Inline Macros

This documentation is for an older version of ZK. For the latest one, please click here.

This documentation is for an older version of ZK. For the latest one, please click here.

There are two kinds of macro components: inline and regular. By default, regular macros are assumed. To specify inline macros, you have to specify inline="true" in the component directive.

An inline macro behaves like inline-expansion. ZK doesn't create a macro component if an inline macro is encountered. Rather, it inline-expands the components defined in the macro URI. In other words, it works as if you type the content of the inline macro directly to the target page.

use.zul: (target page)

<?component name="username" inline="true" macroURI="username.zul"?>
<grid>
	<rows>
		<username id="ua" name="John"/>
	</rows>
</grid>

username.zul: (macro definition)

<row>
	Username
	<textbox id="${arg.id}" value="${arg.name}"/>
</row>

Equivalent page:

<grid>
	<rows>
		<row>
			Username
			<textbox id="ua" value="John"/>
		</row>
	</rows>
</grid>

All properties, including id, are passed to the inline macro.

On the other hand, ZK will create a real component (called a macro component) to represent the regular macro. That is, the macro component is created as the parent of the components that are defined in the macro.

Inline macros are easier to integrate into sophisticated pages. For example, you cannot use regular components in the previous example since rows accepts only row, not macro components. It is easier to access to all components defined in a macro since they are in the same ID space. It also means the developers must be aware of the implementation to avoid name conflicts.

Regular macros allow the component developers to provide additional API and hide the implementation from the component users. Each regular macro component is an ID space owner, so there is no name conflicts. The users of regular macros usually assume nothing about the implementation. Rather, they access via the well-defined API.

An Example

inline.zul: (the macro definition)

<row>
	<textbox value="${arg.col1}"/>
	<textbox value="${arg.col2}"/>
</row>

useinline.zul: (the target page)

<?component    name="myrow"    macroURI="inline.zul"  inline="true"?>
<window    title="Test of inline macros"    border="normal">
	<zscript><![CDATA[
		import    org.zkoss.util.Pair;
		List  infos = new LinkedList();
		for(int j     = 0;j    <10;++j){
			infos.add(new Pair("A" + j, "B" +j));
		}
	]]>
	</zscript>
	<grid>
		<rows>
			<myrow    col1="${each.x}"    col2="${each.y}"    forEach="${infos}"/>
		</rows>
	</grid>
</window>